home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / misc / vinced / include / autodocs / titlebar.doc next >
Text File  |  1999-04-19  |  11KB  |  302 lines
  1. TABLE OF CONTENTS
  2.  
  3. titlebar.image/--background--
  4. titlebar.image/titlebar.image
  5. titlebar.image/ObtainTBIClass
  6. titlebar.image/--background--                   titlebar.image/--background--
  7.  
  8. DESCRIPTION
  9.  
  10. The titlebar.image is a shared library which, when opened, adds to the system
  11. a public BOOPSI image class called "tbiclass". This class implements several
  12. images suitable for the use as imagery of gadgets added to the titlebar of
  13. a window, such as an "iconify" image, a "pop-up" image, and so on. Also, a
  14. general purpose "empty" (border-only) image is provided, to be used as the
  15. background of more specialized titlebar images.
  16.  
  17. The purpose of "tbiclass" is to offer developers an easy way to implement
  18. the most common additional titlebar gadgets without having to draw or
  19. code their imagery themselves, and with the added benefit of standardizing
  20. the size and appearance of this kind of gadgets. For instance, until now
  21. any developer needing an iconify gadget had to hard-code its imagery into
  22. his application, leading to a plethora of similar, but different, versions
  23. of the same gadget.
  24.  
  25. The library is freeware; if you use it, you are allowed to distribute it
  26. with your software, typically as a stand-alone file (you'll just have to
  27. add a section for it in your application's installation script).
  28.  
  29. Using "tbiclass" is very simple: you just need to open the titlebar.image
  30. library in order to add the class to the system, and then close it when you
  31. don't need the class anymore (and have freed all of its instances).
  32.  
  33. Once the class has been added to the system, you can use NewObject() in the
  34. usual way to create new "tbiclass" instances. See the "Class documentation"
  35. section to learn which tags are recognized by the class, as well as more
  36. information about the class in general.
  37.  
  38. Important note: a more refined version of "tbiclass" is also added to the
  39. system at boot time by the VisualPrefs utility (a patch to modify the look
  40. of the Amiga GUI). If the titlebar.image library, when it's opened, finds
  41. that a class named "tbiclass" already exists, it won't create another, but
  42. still will open successfully, so your code does NOT have to change to take
  43. this special case into account.
  44.  
  45. The only thing to remember is, you should NOT open the titlebar.image library
  46. if your program is launched in the Startup-sequence _before_ the line where
  47. VisualPrefs is usually started (which is just before IPrefs), or else the
  48. patch won't run correctly. If you absolutely need to place your program in
  49. the Startup-sequence before VisualPrefs/IPrefs, at least offer the user
  50. an option to avoid opening the titlebar.image library.
  51. Anyway, this shouldn't be a problem for the vast majority of applications...
  52.  
  53.  
  54. CLASS DOCUMENTATION
  55.  
  56. Class:        tbiclass
  57. Superclass:   imageclass
  58. Include File: <images/titlebar.h>
  59.  
  60. This is a class of images suitable for use as imagery of gadgets added to
  61. a window titlebar. As of version 40, there are 6 possible "tbiclass" images
  62. to choose from:
  63.  
  64. POPUPIMAGE          A MUI "pop-up" titlebar gadget image
  65. MUIIMAGE            A MUI "settings" titlebar gadget image
  66. SNAPSHOTIMAGE       A MUI "snapshot" titlebar gadget image
  67. ICONIFYIMAGE        An "iconify" titlebar gadget image
  68. PADLOCKIMAGE        A DirOpus "padlock" titlebar gadget image
  69. TBFRAMEIMAGE        A general-purpose empty titlebar gadget image
  70.  
  71. These image types are an extension to those already offered by "sysiclass";
  72. in fact, "tbiclass" is used mostly the same way as "sysiclass" (see below
  73. for its methods and attributes).
  74.  
  75. It's worth noticing that all "tbiclass" image instances will have an
  76. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  77. place your titlebar gadgets accordingly. The reason for this apparently
  78. strange behavior is that Intuition titlebar gadget images, too, work
  79. this way, and we should try to stay as compatible with Intuition as
  80. possible.
  81.  
  82. Also, make sure you adjust your gadget's size if necessary, to adapt it
  83. to the returned image's size.
  84.  
  85. There are actually two versions of this class: a disk-based one, implemented
  86. by the freely distributable "titlebar.image" library, and another, more
  87. refined, added to the system by the VisualPrefs program at boot time.
  88. Applications needing this class should always ship with the "titlebar.image"
  89. library, and use it without worrying about the presence of VisualPrefs in the
  90. system: if it's running, its "tbiclass" version will be used automatically.
  91.  
  92. The _only_ exception to this rule is when your application is run in the
  93. Startup-sequence before VisualPrefs; in this case, you should offer the
  94. user an option to avoid opening "titlebar.image", otherwise the disk-based
  95. version of the class would be added to the system and VisualPrefs wouldn't
  96. be able to add its own version. This is, however, a very unlikely scenario;
  97. in all foreseeable cases, an application opening windows shouldn't be run
  98. so early in the Startup-sequence.
  99.  
  100. New Methods:
  101.  
  102. None.
  103.  
  104. Changed Methods:
  105.  
  106. OM_NEW - After creation of the image by the superclass, this method
  107. initializes the "tbiclass" instance data on the basis of the contents
  108. of the attributes tag list.
  109.  
  110. OM_DISPOSE - This method frees all the resources allocated in the OM_NEW
  111. method.
  112.  
  113. OM_SET - This method allows to change a few of the image attributes and
  114. checks their bounds integrity.
  115.  
  116. OM_GET - This method allows to retrieve the value of the most relevant
  117. image attributes.
  118.  
  119. IM_DRAW - This method does the actual rendering of the image, taking into
  120. account its various attributes and the screen's DrawInfo pens.
  121.  
  122. IM_DRAWFRAME - Like IM_DRAW, but uses the size specified in the impDraw
  123. message rather than the one in the image structure.
  124.  
  125. Attributes:
  126.  
  127. SYSIA_DrawInfo (IS) - This is absolutely mandatory. You MUST pass a DrawInfo
  128.                       pointer to "tbiclass" or NewObject() will fail.
  129.  
  130. SYSIA_Which (ISG) - To specify which image you want; currently there are six
  131.                     image types, defined in <images/titlebar.h>: POPUPIMAGE,
  132.                     MUIIMAGE, SNAPSHOTIMAGE, ICONIFYIMAGE, PADLOCKIMAGE and
  133.                     TBFRAMEIMAGE.
  134.  
  135. IA_Width, IA_Height (ISG) - Only recognized by the TBFRAMEIMAGE type; the
  136.                             other image types ignore them and always have
  137.                             the same size of the depth gadget image.
  138.  
  139. SYSIA_ReferenceFont (IS) - This is only recognized by the TBFRAMEIMAGE type;
  140.                            the other image types ignore it and always have
  141.                            the same height of the depth gadget image. It's
  142.                            also ignored if IA_Height is explicitly used.
  143.  
  144.  
  145. PROGRAMMING EXAMPLE
  146.  
  147. An example of usage of "titlebar.image" and "tbiclass" could be given by
  148. the following code fragment:
  149.  
  150.    ...
  151.    #include "images/titlebar.h"
  152.    #include "clib/titlebarimage_protos.h"
  153.    #include "pragmas/titlebarimage_pragmas.h"
  154.  
  155.    ...
  156.    
  157.    struct Library *TitlebarImageBase;
  158.  
  159.    ...
  160.  
  161.    /* Open the library */
  162.    
  163.    if (!(TitlebarImageBase = OpenLibrary("Images/titlebar.image",40)))
  164.    {
  165.       ComplainAndExit();
  166.    }
  167.  
  168.    ...
  169.  
  170.    /* Create the image */
  171.  
  172.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  173.                                                   SYSIA_DrawInfo,dri,
  174.                                                   TAG_END)))
  175.    {
  176.       iconifyimage = builtin_iconifyimage;  /* If really needed... */
  177.    }
  178.  
  179.    /* Use the image */
  180.  
  181.    gad->GadgetRender = iconifyimage;
  182.    ...
  183.  
  184.    /* Free the image */
  185.  
  186.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  187.  
  188.    ...
  189.    
  190.    /* Close the library */
  191.    
  192.    CloseLibrary(TitlebarImageBase);
  193.    
  194.    ...
  195.  
  196. A complete example program can also be found in the distribution archive.
  197.  
  198.  
  199. TO DO
  200.  
  201. Future releases should add the following features:
  202.  
  203.  o More image types.
  204.  
  205.  o Some more code optimization.
  206.  
  207. And of course, I'm open to any suggestion about how to improve the class.
  208.  
  209.  
  210. AUTHOR
  211.  
  212. Massimo Tantignone
  213. Via Campagnoli, 4
  214. 28100 Novara (NO)
  215. ITALY
  216.  
  217. E-mail: tanti@intercom.it
  218. Web:    http://www.intercom.it/~amigaws
  219.  
  220. titlebar.image/titlebar.image                   titlebar.image/titlebar.image
  221.  
  222.    NAME
  223.       titlebar.image -- create an image suitable for titlebar gadgets
  224.  
  225.    FUNCTION
  226.       The titlebar.image shared library implements a public BOOPSI image
  227.       class, called "tbiclass", which provides the most commonly used images
  228.       for gadgets added by applications to the titlebar of their windows.
  229.       Examples of this are the ubiquitous "iconify" gadget or DirOpus 5's
  230.       "padlock" gadget.
  231.       
  232.       All programs using such class will automatically get the same look for
  233.       their titlebar images. This is probably better than having myriads of
  234.       different versions of the same image...
  235.       
  236.       The titlebar.image library is freeware; the idea is that if your
  237.       software needs images for gadgets in window titlebars, you can simply
  238.       place the library into your distribution archive and let the user
  239.       install it to his machine alongside your application, which will then
  240.       be able to open and use it.
  241.  
  242.       You can use "tbiclass" just like "sysiclass"; they're both sub-classes
  243.       of "imageclass". A "tbiclass" image can be created in the usual way,
  244.       by calling NewObject() with the tags described in the class reference
  245.       documentation.
  246.  
  247.       Of course, if NewObject() fails, you should provide a built-in fallback
  248.       image for your titlebar gadget. However, as this occurrence isn't very
  249.       likely (the class requires very little memory), you can keep your
  250.       built-in images very simple.
  251.  
  252.       To be able to create and use "tbiclass" objects in an application,
  253.       you first have to open the titlebar.image library with OpenLibrary().
  254.       Once you have done this, you shouldn't close the library until all of
  255.       your "tbiclass" objects have been freed.
  256.  
  257.       For a complete description of the "tbiclass" class and its features,
  258.       see the class reference documentation in the --background-- paragraph.
  259.  
  260.    TAGS
  261.       For the full list of "tbiclass" attributes, see the class reference
  262.       documentation in the --background-- paragraph.
  263.  
  264.    WARNING
  265.       Don't close the titlebar.image library if you still have some instances
  266.       of "tbiclass" images hanging around!
  267.  
  268.    BUGS
  269.       None known.
  270.  
  271. titlebar.image/ObtainTBIClass                   titlebar.image/ObtainTBIClass
  272.  
  273.    NAME
  274.       ObtainTBIClass -- return a pointer to "tbiclass".
  275.  
  276.    SYNOPSIS
  277.       tbiclass = ObtainTBIClass()
  278.       D0
  279.  
  280.       Class *ObtainTBIClass(void);
  281.  
  282.    FUNCTION
  283.       Returns a pointer to the class implemented by the titlebar.image,
  284.       called "tbiclass". Use this pointer with care, and do not reference it
  285.       after you've closed the titlebar.image library.
  286.       
  287.    INPUTS
  288.       none
  289.  
  290.    RESULT
  291.       tbiclass - pointer to the class
  292.  
  293.    NOTES
  294.       If VisualPrefs is running, you will obtain a pointer to its special
  295.       version of "tbiclass".
  296.  
  297.    BUGS
  298.       None known.
  299.  
  300.    SEE ALSO
  301.  
  302.